home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr46 / multi_c1.zip / MULTI_C.DOC < prev    next >
Text File  |  1992-11-08  |  59KB  |  2,311 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                 MULTI-APP V1.0.1
  7.                          ==============================
  8.  
  9.                          ______________________________
  10.  
  11.                          ==============================
  12.  
  13.                              Documentation Rev 0.3
  14.                          Copyright 1992 by Jeff Heaton
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                                  MULTI-APP V1.0
  23.                              A MicroGenesis Product
  24.                          Copyright 1992 by Jeff Heaton
  25.                               All Rights Reserved
  26.  
  27.                              MicroGenesis Software
  28.                                P.O. Box No 25534
  29.                               St. Louis, MO 63125
  30.  
  31.                              VOICE: (314) 638-2506
  32.                       DATA:(314) 638-5205 n,8,1,1200-9600
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.     Part I: The Multi-APP Core
  72.  
  73.     Introduction
  74.  
  75.      The MULTI-APP core is the heart of the MULTI-APP system.  All classes
  76.     in the MULTI-APP system are derived from these "core classes." The
  77.     primary purpose of this core is to give all MULTI-APP classes a
  78.     consistent interface.  Many abstract classes(who
  79.     se sole purpose is to define future classes) are defined here, as well
  80.     as real classes for file and data handling.
  81.  
  82.      Using the MULTI-APP core you can provide your application with
  83.     platform-independent access to the basic system resources that all
  84.     applications need.  These are the file system, the serial ports, and
  85.     basic data structure handling.  In addition a spec
  86.     ial "error free" compression based communications protocol is provided
  87.     to allow you to access other MULTI-APP applications and share
  88.     information remotely.
  89.  
  90.      In addition to providing these basic services, MULTI-APP core allows
  91.     you to use the MULTI-APP user interface package to produce GUI(graphic
  92.     user interface) applications in a platform-independent manner.
  93.  
  94.     MultiApp Core Features:
  95.  
  96.      I. Platform Independent Access to Files:
  97.       A. DEVICE compatible for I/O redirection
  98.       B. Allows concurrent shared access of files
  99.       C. Buffered character access provides maximum speed
  100.       D. Fast block read/write functions for record handling
  101.      II. Platform Independent Access to Serial Ports:
  102.       A. DEVICE compatible for I/O redirection
  103.       B. Optional Compression/Error correction(in SOFTWARE)
  104.       C. Access to all hardware lines provided by host computer
  105.      III. Misc Platform Independent Services:
  106.       A. Integer stacks
  107.       B. Base classes for linked lists
  108.       C. File Maintenance functions
  109.  
  110.  
  111.     License
  112.  
  113.      The MultiApp system is currently being marketed as ShareWare.
  114.     Shareware is a unique software distribution method where you, the
  115.     software user, gets to try out the program BEFORE you pay for it.  This
  116.     is a FULL version of the MultiApp core, and you
  117.     get a FULL copy of the text representation of the user manual to
  118.     evaluate for a time period of 30(thirty) days.  If you wish to continue
  119.     using MultiApp after this trial period, or if you publicly release a
  120.     program(commercial,shareware, public domain
  121.     or any other non-personal use) you MUST register your copy.  Upon
  122.     registration you will receive the complete source code to the MultiApp
  123.     product that you registered.  The source code, however, will be for
  124.     your exclusive use and may not be distributed
  125.      directly.  However, applications can be created using source code
  126.     modifications.
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.      If you use MultiApp beyond the initial 30 day limit, or publicly
  138.     release any application that contains MultiApp code you MUST have
  139.     registered MultiApp.  To do otherwise is a direct violation of the
  140.     MultiApp copyright.  However once you have register
  141.     ed a MultiApp product you may use it in your own application, royalty
  142.     free, for as many applications as you wish.
  143.  
  144.      The following information is not in classes and provide miscellaneous
  145.     utility to the MULTI-APP system.  Some of the data structures defined
  146.     here are only used in the MULTI-APP user interface and are thus only
  147.     briefly described.
  148.  
  149.     Contacting MicroGenesis:
  150.     Compuserve  : 76476,1701
  151.     America On-Line : JeffH66
  152.     InterNet  : S108955@UMRVMA.UMR.EDU
  153.     Voice   : (314) 638-2506
  154.     BBS   : (314) 638-1731
  155.  
  156.  
  157.     Compiler Considerations:
  158.      If you want to maximize portablilty between various computer platforms
  159.     MultiApp can greatly speed this process.  However because even C/C++
  160.     compilers interpret the C/C++ standard differently you must account for
  161.     these differences in your code.  Thes
  162.     e are generally only syntactical errors that will show up when you
  163.     compile your application on another platform for the first time.
  164.  
  165.      MultiApp does not use pure c++ as its coding standard.  Pure C++ can
  166.     defiantly be used with MultiApp but since many platforms(particularly
  167.     the Macintosh) are lacking in the area of quality C++ compilers we have
  168.     developed MultiApp based on a simpler
  169.     subset of C++.  This is based on Symantec Think C 5's objects
  170.     extension.  This is basically identical to C++ but without some of
  171.     C++'s more complex features.  IF you want your application to be
  172.     directly compilable on object based C compilers you shou
  173.     ld not use the following C++ features:
  174.  
  175.      Function Overloading
  176.      Operator Overloading
  177.      Function Templates
  178.      Parameters To Constructors
  179.      Static Objects(ie MYOBJECT obj; is illegal it MUST be
  180.         MYOBJECT *obj)
  181.      this redefinition(this=this->next is illegal, all other standard this
  182.     operations are legal however).
  183.      All Functions MUST have prototypes.
  184.      Cast all pointer conversions
  185.  
  186.      These are some general rules to follow to ensure that your programs
  187.      are compatible with Object C type compilers as well as True C++
  188.      compilers.  Once multiApp is ported into C++ compilers on both Dos and
  189.      Mac these restrictions will not be necessary.
  190.      We are currently working on creating a MPW version of MutliApp that
  191.      will support full C++, but for now please remember that not all
  192.      platforms have as "developed" of a base of C++ compilers as the IBM
  193.      platform does.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.      If you are going to be seriously developing cross-platform
  204.     applications than it is suggested that you own a copy of BOTH
  205.     Borland/Turbo C++ and Think C so you can see the differences for
  206.     yourself.  I have not found it to be too much of a problem in o
  207.     ur own development.  Just treat Think C as the "least common
  208.     denominator" and you will do fine.  We will also be coming out with a
  209.     document further describing Think C/Borland C++ compatibility with the
  210.     release of MultiApp UI.
  211.  
  212.  
  213.     Global Functions:
  214.     void beep(void);
  215.      This function will cause the users computer to beep.
  216.  
  217.     void c2pas(char *str);
  218.      This function will transform str  into a pascal string(assuming it was
  219.     originally a c string).
  220.  
  221.     void pas2c(char *str);
  222.      This function will transform str  into a c string(assuming it was
  223.     originally a pascal string).
  224.  
  225.     void sleep(int tenths);
  226.      This function will wait for tenths 1/10ths of a second.
  227.  
  228.     int timer_check(long tm);
  229.      Call this function,with the value timer_set returns, to see if the
  230.     time is up.  If that time has elapsed then this function returns true.
  231.  
  232.     long timer_set(int tenths);
  233.      Sets a timer for tenths 1/10ths of a second.  The value that this
  234.     function returns should be passed to timer_check to determine if that
  235.     time has elapsed.
  236.  
  237.     void timer_wait(long tm);
  238.      Call this function with the value timer_set returns to wait until that
  239.     amount of time elapses.
  240.  
  241.     void updcrc(unsigned char b);
  242.      Each call of this function causes b to be calculated into the global
  243.     crc.
  244.  
  245.     extern unsigned short crc;
  246.      This variable is used with updcrc  to calculate a CRC value.  After
  247.     you are done feeding updcrc your bytes, this is the variable you get
  248.     your final CRC from.
  249.  
  250.  
  251.  
  252.  
  253.     Definitions:
  254.  
  255.     The following are some general integer to binary conversion functions
  256.     that allow MULTI-APP data to be compatible across platforms(especially
  257.     since Intel and Motorola store ints exactly backwards of each other):
  258.     #define HI_BYTE(x) (x/256)
  259.     #define LO_BYTE(x) (x-(HI_BYTE(x)*256))
  260.     #define BYTE_COMB(x,y) ((x*256)+y)
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.     CLASS NAME: ATOM       PARENT: NONE
  270.     IMPORTANT CHILDREN: almost the whole library.
  271.  
  272.     Definition:
  273.  
  274.     class ATOM
  275.     {
  276.      public:
  277.      ATOM();
  278.  
  279.      ATOM *next;// Next atom in a linked list
  280.     };
  281.  
  282.     Description:
  283.  
  284.         The most fundamental class of MULTI-APP is the atom class.  Every
  285.     object in the MULTI-APP library is derived from the atom class.  This
  286.     allows general purpose "data container classes" to be defined for the
  287.     atom.  These data container classes can
  288.     then be used for other object types as well.  The most important of
  289.     these data container classes is the linked list class(LIST). In its
  290.     simplest form LIST allows a linked list of ATOM's,  but because WINDOW
  291.     classes are derived from ATOM it is possibl
  292.     e to create a linked list of WINDOWs or any other descendant of the
  293.     ATOM class.
  294.  
  295.     Member Functions:
  296.      ATOM();
  297.       Description:
  298.       CONSTRUCTOR - simply sets next equal to NULL.
  299.  
  300.       Returns:
  301.       nothing
  302.  
  303.       See Also:
  304.  
  305.       Example:
  306.        int search_for(ATOM *first,ATOM *lookfor)
  307.         {
  308.         // Search the linked list pointed to by "first" for
  309.         // "lookfor".  Return TRUE if found
  310.  
  311.         while(first!=NULL)
  312.          {
  313.          if(first==lookfor)// Found it yet?
  314.           return TRUE;
  315.          first=first->next;// Next atom in list
  316.          }
  317.         }
  318.  
  319.     Data Members:
  320.      ATOM *next;
  321.       The next ATOM in the linked list.
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.     CLASS NAME: LIST       PARENT: ATOM
  336.     IMPORTANT CHILDREN:  APP(from the user interface)
  337.     Definition:
  338.  
  339.     class LIST:public ATOM
  340.     {
  341.      public:
  342.  
  343.      LIST(void);
  344.  
  345.      void add(ATOM *atom);
  346.      void del(ATOM *atom);
  347.  
  348.      void first_element(void);
  349.      void forward(void);
  350.      void pos(long p);
  351.      virtual int  comp(ATOM *a1,ATOM *a2);
  352.  
  353.      ATOM *first,*current;
  354.     };
  355.  
  356.     Description:
  357.  
  358.      The LIST object is one of the primary classes of MULTI-APP.  LIST is a
  359.     "data container object" designed to hold a linked list of ATOMS.
  360.     Because almost every object in MULTI-APP is derived from ATOM, lists
  361.     can be built of many different types of obj
  362.     ects.  For example in the MULTI-APP User Interface section you will
  363.     learn that the APP class is really a linked list of all open windows.
  364.     Because APP is a child of LIST it can build lists of ANYTHING that is
  365.     derived from ATOM.  This includes windows
  366.     , dialogs and many other types of screen objects.
  367.  
  368.     Data Members:
  369.      ATOM *first;
  370.       This is the first ATOM in the linked list.  This gives LIST a
  371.     starting point for list resets and searches.  If the list is empty then
  372.     this variable contains a NULL.
  373.      ATOM *current;
  374.       Current is the atom that the list is currently processing.  It is
  375.     perfectly legal for current to be NULL, even if the list has data in
  376.     it.  A NULL current usually means  that you have reached the end of the
  377.     list.
  378.  
  379.  
  380.     Member Functions:
  381.  
  382.      LIST(void);
  383.       Description:
  384.       CONSTRUCTOR - This sets current and first to NULL, thus creating a
  385.       new blank LIST.
  386.  
  387.       Returns:
  388.       nothing
  389.  
  390.       See Also:
  391.        ATOM
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.       Example:
  402.        void main(void)
  403.         {
  404.         LIST *list;// The list we will be adding items to
  405.         ATOMS *a,*b,*c; // Some atoms to add
  406.  
  407.         list=new LIST;
  408.         list->add(a=new ATOM);
  409.         list->add(b=new ATOM);
  410.         list->add(b=new ATOM);
  411.  
  412.         // At this point the list would look something like:
  413.         // a-->b-->c-->NULL
  414.  
  415.         list->del(b);
  416.  
  417.         // At this point the list would look something like:
  418.         // a-->c-->NULL
  419.  
  420.         // Now loop through the list
  421.  
  422.         first_element();
  423.         while(current!=NULL)
  424.          forward();
  425.         }
  426.  
  427.     _________________________________________________________
  428.      void add(ATOM *atom);
  429.       Description:
  430.        atom - The atom being added to list.
  431.       This function adds a new ATOM into the list.  The comp function is
  432.     used to determine atom's position.  If comp  is not redefined then the
  433.     atom is inserted at the end of the list.
  434.  
  435.       Returns:
  436.       nothing
  437.  
  438.       See Also:
  439.        del
  440.        Example for LIST class.
  441.  
  442.       Example:
  443.        void MYOBJECT::add(ATOM *atom)
  444.         {// An add function for a derived LIST manager
  445.         MYITEM *i=(MYITEM*)atom;
  446.  
  447.         // Now use "i" to officially add your type of object
  448.         // This is usually some sort of inititilaztion
  449.  
  450.         LIST::add(atom);// Add it to the actual list
  451.         }
  452.  
  453.  
  454.     _________________________________________________________
  455.      virtual int  comp(ATOM *a1,ATOM *a2);
  456.       Description:
  457.        a1 - The atom on the left side of the comparison
  458.        a2 - The atom on the right side of the comparison
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.       This function compares a1  to a2  and returns:
  469.       0   Both ATOMS are equal.
  470.       >1  a1 is greater than a2
  471.       <1  a2 is greater than a1
  472.       Comp is used to sort ATOMS as they enter the list.
  473.  
  474.       Returns:
  475.       nothing
  476.  
  477.       See Also:
  478.        forward()
  479.        Example for LIST class.
  480.  
  481.       Examples:
  482.  
  483.        // A compare function(the default) that will insert items into the
  484.        list in reverse order.
  485.        int class::comp(ATOM *a1,ATOM *a2){ return 1; }
  486.  
  487.        // A compare function that will insert items in the same order they
  488.        are entered
  489.        int class::comp(ATOM *a1,ATOM *a2){ return  -1; }
  490.  
  491.     _________________________________________________________
  492.      void del(ATOM *atom);
  493.       Description:
  494.        atom - The atom being removed from the list.
  495.       This function removes an ATOM from the list.  Please note that the
  496.     memory for atom  is not freed, but rather the ATOM is simply pulled out
  497.     of the list chain.
  498.       Returns:
  499.       nothing
  500.  
  501.       See Also:
  502.        add
  503.        Example for LIST class.
  504.  
  505.       Example:
  506.        void MYOBJECT::del(ATOM *atom)
  507.         {// An del function for a derived LIST manager
  508.         MYITEM *i=(MYITEM*)atom;
  509.  
  510.         // Now use "i" to officially remove  your type of object
  511.         // This is usually some sort of shutdown sequence
  512.  
  513.         LIST::del(atom);// Add it to the actual list
  514.         }
  515.  
  516.  
  517.     _________________________________________________________
  518.      void first_element(void);
  519.       Description:
  520.       This function sets current  to first, thus moving the lists attention
  521.       to its first element.  This function is usually called prior to a
  522.       search.
  523.  
  524.       Returns:
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.       nothing
  534.  
  535.       See Also:
  536.        forward()
  537.        Example for LIST class.
  538.  
  539.  
  540.     _________________________________________________________
  541.      void forward(void);
  542.       Description:
  543.       This function moves the current pointer to the next ATOM in the list.
  544.       If there are no more ATOMs or the list is empty then current is set
  545.       to NULL.
  546.  
  547.       Returns:
  548.       nothing
  549.  
  550.       See Also:
  551.        first_element()
  552.        Example for LIST class.
  553.     _________________________________________________________
  554.      void pos(long p);
  555.       Description:
  556.        p - element in list to move to.
  557.       This function moves(points current to) the "p"th element in the
  558.     linked list.
  559.       Returns:
  560.       nothing
  561.  
  562.       See Also:
  563.        forward
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.     CLASS NAME: DEVICE       PARENT: LIST
  600.     IMPORTANT CHILDREN: FILEIO, and any device class made for MULTI-APP
  601.  
  602.     Definition:
  603.  
  604.     class DEVICE:public LIST
  605.     {
  606.      public:
  607.      virtual int put(BYTE ch);
  608.      virtual int putstr(char *str);
  609.      virtual int goxy(int x,int y);
  610.      virtual int inverse(void);
  611.      virtual int normal(void);
  612.      virtual BYTE get(BYTE *ch);
  613.      virtual BYTE wait2get(BYTE *ch);
  614.      virtual int hit(void);
  615.      virtual int reset(void);
  616.      virtual int ceol(void);
  617.      virtual int wherex(void);
  618.      virtual int wherey(void);
  619.      virtual int printf(char *format,...);
  620.      int getstr(char *str);
  621.     };
  622.  
  623.  
  624.     Description:
  625.      DEVICE is a object that defines basic properties that any MULTI-APP
  626.     compatible device should have.  DEVICE allows MULTI-APP to communicate
  627.     to a device in a polled 8-bit manner.  Commands are provided to do
  628.     basic byte I/O as well as some general cont
  629.     rol commands that many "video" devices would have.  The commands
  630.     provided here are the same on ALL the children of DEVICE.  So as a
  631.     result the command to print a string is identical in all parts of
  632.     MULTI-APP.
  633.  
  634.  
  635.  
  636.     Data Members:
  637.      NONE
  638.  
  639.     Member Functions:
  640.      virtual int ceol(void);
  641.       Description:
  642.       Ceol is only used in video devices, it will clear to the end of the
  643.       line starting at wherex,wherey.
  644.  
  645.       Returns:
  646.       nonzero on error.
  647.  
  648.       See Also:
  649.        reset.
  650.  
  651.  
  652.     _________________________________________________________
  653.      int getstr(char *str);
  654.       Description:
  655.        str - the string read from the device.
  656.       This function will input characters into the string str until a
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.     carriage return(#13) is received.  The final carriage return is not
  666.     stored in the string. If the operation is successful this function will
  667.     return a zero.
  668.  
  669.       Returns:
  670.       nonzero on error.
  671.  
  672.       See Also:
  673.  
  674.  
  675.     _________________________________________________________
  676.      virtual BYTE get(BYTE *ch);
  677.       Description:
  678.        ch - if NULL does nothing, otherwise the BYTE read.
  679.       This function receives the next 8-bit character from the device.  If
  680.     none are available then this function returns a zero.  There are two
  681.     paths by which this function returns its data.  First is through the
  682.     normal function return, and second is via
  683.      a pointer to a BYTE.  If you do not wish to use the pointer method
  684.     simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
  685.     "x=get(&x)" all do exactly the same thing.
  686.  
  687.       Returns:
  688.       character read, or a zero if none are available.
  689.  
  690.       See Also:
  691.        put,getstr,wait2get,hit.
  692.  
  693.       Example:
  694.        BYTE DEVICE::wait2get(BYTE *ch)
  695.         {
  696.         BYTE c;
  697.         while(!hit());// Loop until something is available
  698.         c=get(NULL);// Input character
  699.  
  700.         if(ch!=NULL)// Return by pointer if necessary
  701.          *ch=c;
  702.  
  703.         return(c);
  704.         }
  705.  
  706.     _________________________________________________________
  707.      virtual int goxy(int x,int y);
  708.       Description:
  709.        x - The horizontal position to goto.
  710.        y - The vertical position to goto.
  711.       This function allows you to set the x and y coordinates of the
  712.     device.  Not all devices have x/y coordinates, so this function is not
  713.     used in all DEVICES.  If the operation is successful this function will
  714.     return a zero.
  715.  
  716.       Returns:
  717.        nonzero on error.
  718.  
  719.       See Also:
  720.        reset.
  721.  
  722.       Example:
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.        void home(DEVICE *d)
  732.         {// Home the cursor in any device(if it supports cursors)
  733.         d->goxy(0,0);
  734.         }
  735.  
  736.     _________________________________________________________
  737.      virtual int hit(void);
  738.       Description:
  739.       Hit allows you to determine if there is a character waiting to be
  740.       received(by one of the input functions).  Hit returns 0 if none are
  741.       available. If data is waiting it returns the number of bytes waiting.
  742.  
  743.       Returns:
  744.       true if there is a character waiting to be read.
  745.  
  746.       See Also:
  747.        get,wait2get.
  748.  
  749.       Example:
  750.        see get.
  751.  
  752.  
  753.  
  754.     _________________________________________________________
  755.      virtual int inverse(void);
  756.       Description:
  757.       If the device is capable of having its foreground and background
  758.       colors inverted this function inverses them.  If the operation is
  759.       successful then this function will return a zero.   Inverse is left
  760.       over from before MULTI-APP supported color, and i
  761.     s rarely used anymore.
  762.  
  763.       Returns:
  764.        nonzero on error.
  765.  
  766.       See Also:
  767.        normal.
  768.  
  769.     _________________________________________________________
  770.      virtual int normal(void);
  771.       Description:
  772.       This function resets any special modes(namely inverse) that may have
  773.       been set on this device.  If the operation is successful this
  774.       function will return a zero.
  775.  
  776.       Returns:
  777.        nonzero on error.
  778.  
  779.       See Also:
  780.        inverse.
  781.  
  782.     _________________________________________________________
  783.      virtual int printf(char *format,...);
  784.       Description:
  785.        format - "stdio.h printf" format string to write.
  786.       This output function allows you to output to a device in the classic
  787.     C printf style.  Consult your C reference manual if you require
  788.     additional information on printf.  Please note that the final outputted
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.     string cannot be larger than 199 characters
  798.     , if it is the results are undefined.
  799.  
  800.       Returns:
  801.       nonzero on error.
  802.  
  803.       See Also:
  804.       put,putstr.
  805.  
  806.       Example:
  807.        void main(void)
  808.         {
  809.         DEVICE *device;
  810.  
  811.         device=new DEVICE;
  812.         device->goxy(10,10);// Move cursor
  813.  
  814.         device->printf("Cursor is at: %xi,%i.",// Display cursor's location
  815.          device->wherex(),device->wherey());
  816.         }
  817.  
  818.  
  819.  
  820.  
  821.     _________________________________________________________
  822.      virtual int put(BYTE ch);
  823.       Description:
  824.        ch - the character to be written.
  825.       This function will attempt to write a single character to the device.
  826.     If the operation is successful this function will return a zero.
  827.       Returns:
  828.        nonzero on error.
  829.  
  830.       See Also:
  831.        putstr,printf.
  832.  
  833.       Example:
  834.        void spc(DEVICE *device,int i)
  835.         {// write out i spaces(32) to any type of device
  836.         while(i--)
  837.          d->put(32);
  838.         }
  839.  
  840.     _________________________________________________________
  841.      virtual int putstr(char *str);
  842.       Description:
  843.        str - the string to be written.
  844.       This function repeatedly calls put  until a zero is reached in the
  845.     string.    If the operation is successful this function will return a
  846.     zero.
  847.  
  848.       Returns:
  849.        nonzero on error.
  850.  
  851.       See Also:
  852.        put,printf
  853.  
  854.       Example:
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.        int DEVICE::printf(char *format, ... )
  864.         {// The printf function from DEVICE
  865.         char string[200];
  866.         va_list ptr;
  867.  
  868.         va_start(ptr,format);
  869.         vsprintf(string,format,ptr);
  870.         putstr(string);
  871.         va_end(ptr);
  872.         return 0;
  873.         }
  874.  
  875.     _________________________________________________________
  876.      virtual int reset(void);
  877.       Description:
  878.       Reset acts very different based on the device.  On most video devices
  879.       it will clear the screen, while on others it flushes all I/O buffers.
  880.  
  881.       Returns:
  882.       nonzero on error.
  883.  
  884.       See Also:
  885.        goxy.
  886.  
  887.  
  888.  
  889.  
  890.     _________________________________________________________
  891.      virtual BYTE wait2get(BYTE *ch);
  892.       Description:
  893.        ch - if NULL does nothing, otherwise the BYTE read.
  894.       This function enters a loop to wait for a character to be available
  895.     then receives the next 8-bit character from the device.  There are two
  896.     paths by which this function returns its data.  First is through the
  897.     normal function return, and second is vi
  898.     a a pointer to a BYTE.  If you do not wish to use the pointer method
  899.     simply call it as "get(NULL)".  Example: "wait2get(NULL)",
  900.     "wait2get(&x)" and "x=wait2get(&x)" all do exactly the same thing.
  901.     WARNING:  This function can hang the system if no char
  902.     acter ever becomes available.
  903.  
  904.       Returns:
  905.        character read.
  906.  
  907.       See Also:
  908.        put,getstr,hit.
  909.  
  910.       Example:
  911.        see get.
  912.  
  913.  
  914.  
  915.     _________________________________________________________
  916.      virtual int wherex(void);
  917.       Description:
  918.       The wherex function will return the x coordinate of this device.
  919.  
  920.       Returns:
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.       nonzero on error.
  930.  
  931.       See Also:
  932.       wherey,reset,goxy.
  933.  
  934.       Example:
  935.        void main(void)
  936.         {
  937.         DEVICE *device;
  938.  
  939.         device=new DEVICE;
  940.         device->goxy(10,10);// Move cursor
  941.  
  942.         device->printf("Cursor is at: %xi,%i.",// Display cursor's location
  943.          device->wherex(),device->wherey());
  944.         }
  945.  
  946.  
  947.  
  948.     _________________________________________________________
  949.      virtual int wherey(void);
  950.       Description:
  951.       The wherey function will return the y coordinate of this device.
  952.  
  953.       Returns:
  954.       nonzero on error.
  955.  
  956.       See Also:
  957.       wherex,reset,goxy.
  958.  
  959.       Example:
  960.        void main(void)
  961.         {
  962.         DEVICE *device;
  963.  
  964.         device=new DEVICE;
  965.         device->goxy(10,10);// Move cursor
  966.  
  967.         device->printf("Cursor is at: %xi,%i.",// Display cursor's location
  968.          device->wherex(),device->wherey());
  969.         }
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.     CLASS NAME: COMIO       PARENT: DEVICE
  996.     IMPORTANT CHILDREN: ALP
  997.  
  998.     Definition:
  999.     class COMIO:public DEVICE
  1000.     {
  1001.         public:
  1002.      COMIO(void);
  1003.      ~COMIO();
  1004.      int init(int p);
  1005.      virtual int put(BYTE ch);
  1006.      virtual BYTE get(BYTE *ch);
  1007.      virtual int putstr(char *str);
  1008.      virtual int hit(void);
  1009.      virtual void baud(long r);
  1010.      virtual void disconnect(void);
  1011.      virtual int timed_get(BYTE *ch,int secs);
  1012.  
  1013.      void flush_out(void);
  1014.      void flush_in(void);
  1015.      void purge_out(void);
  1016.      void purge_out(void);
  1017.      void flow(int i);
  1018.  
  1019.      void dtr(int i);
  1020.      char carrier(void);
  1021.  
  1022.      int direct,no_modem;
  1023.      long lockbaud;
  1024.      long baudrate,bps;
  1025.         private:
  1026.      Varies with operating system.
  1027.     };
  1028.  
  1029.     Description:
  1030.      COMIO provides a platform-independent method for communicating with
  1031.     the computer's serial ports. COMIO follows the strict interface
  1032.     definition defined by the DEVICE class, and is consistent with all
  1033.     other MULTI-APP classes in that way.  You can spec
  1034.     ify many additional arguments that are compatible only with a serial
  1035.     device, yet all serial I/O is compatible with the DEVICE class.
  1036.     Hardware comport numbers always start at 1.
  1037.  
  1038.     Data Members:
  1039.       long baudrate
  1040.        The baud rate that the remote modem is at, regardless of locked
  1041.     baudrate.  This must be maintained by the user if it is needed.
  1042.  
  1043.       long bps
  1044.        The port's baud rate, if baud rate is locked then this should never
  1045.     be different than lockbaud.  This value is set internally by MultiApp
  1046.     and is meant for reference only.
  1047.  
  1048.       char detect_carrier
  1049.        If this value is true then the carrier function returns the status
  1050.     of the carrier pin.  If this value is false then carrier always returns
  1051.     true.
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.       int direct
  1062.        If this value is one then the COMIO object will do all of its
  1063.     communication at the most direct level possible.  On Mac this would be
  1064.     through the serial manager, on Dos this would mean through interrupts
  1065.     and ports.  If this value is zero then the C
  1066.     OMIO object will do all of its communication at a higher level. On Mac
  1067.     this would still be through the serial manager, on dos this would be
  1068.     through BIOS or a FOSSIL if one is loaded.   Generally you should set
  1069.     this as 1.   WARNING: never change this
  1070.     value once init has been called.
  1071.  
  1072.  
  1073.       long lockbaud
  1074.        This variable allows you to lock the baud rate at some speed.  If
  1075.     you set it to zero(the default) then baud rate is variable.  Some 9600
  1076.     baud modems require their baud rate to be locked at 38,400 baud, this
  1077.     function makes the use of such modems ea
  1078.     sier.
  1079.  
  1080.  
  1081.       int no_modem
  1082.        If this variable is set to one then no communication with the serial
  1083.     ports is made.  This provides for a sort of test mode.
  1084.  
  1085.  
  1086.       port
  1087.        Serial port number that this instance of COMIO is working with.
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.     Member Functions:
  1094.      COMIO(void);
  1095.       Description:
  1096.       CONSTRUCTOR - Allocates any memory needed for buffers.
  1097.  
  1098.       Returns:
  1099.       nothing.
  1100.  
  1101.       See Also:
  1102.       ~COMIO.
  1103.  
  1104.       Example:
  1105.       // VTERM is a simple tty terminal that must be provided with a DEVICE
  1106.       to use
  1107.       // as a console.  This console is usually something such as the UI's
  1108.       CONIO object
  1109.       // however it can really be anything, even another COMIO(which would
  1110.       provide a
  1111.       // remote terminal.  Press \ for a list of commands in this terminal.
  1112.       void vterm(DEVICE *con,COMIO *com)
  1113.       {
  1114.       // con - console device
  1115.       // com - "modem" interface
  1116.       int done=0;
  1117.       char ch;// Check for commands
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.        com->baud(2400);// Default to 2400 baud
  1128.  
  1129.        while(!done)
  1130.         {
  1131.         if(con->hit())// Output keypress
  1132.          {
  1133.          ch=con->get(NULL);
  1134.          if(ch!='\')
  1135.           com->put(con->get(NULL));
  1136.          }
  1137.  
  1138.         if(com->hit())// Display incoming data
  1139.          con->put(com->get(NULL));
  1140.  
  1141.         if(ch=='\')
  1142.          {
  1143.          char str[100];
  1144.          con->reset();
  1145.          con->putstr("Select an option: <B>aud <D>isconnect or <Q>uit? ");
  1146.          switch( toupper(con->wait2get(NULL)))
  1147.           {
  1148.           case Q':done=1;break;
  1149.           case D':com->disconnect();break;
  1150.           case B':con->putstr("\rWhat baud? ");
  1151.            con->getstr(str);
  1152.            con->baud(atoi(str));
  1153.            break;
  1154.           }
  1155.          }
  1156.         }
  1157.       }
  1158.  
  1159.  
  1160.     _________________________________________________________
  1161.      ~COMIO();
  1162.       Description:
  1163.       DESTRUCTOR - Releases any allocated memory, and closes the hardware
  1164.       serial port.
  1165.  
  1166.       Returns:
  1167.       nothing.
  1168.  
  1169.       See Also:
  1170.       COMIO.
  1171.  
  1172.     _________________________________________________________
  1173.      virtual void baud(long r);
  1174.       Description:
  1175.        r - The baud rate that you wish to use.
  1176.       Commands the hardware comport to do all I/O at r  baud rate.
  1177.  
  1178.       Returns:
  1179.       nonzero on error.
  1180.  
  1181.       See Also:
  1182.       init.
  1183.  
  1184.       Example:
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.        see constructor example.
  1194.  
  1195.     _________________________________________________________
  1196.      virtual void baud(long r);
  1197.       Description:
  1198.        r - The baud rate that you wish to use.
  1199.       Commands the hardware comport to do all I/O at r  baud rate.
  1200.  
  1201.       Returns:
  1202.       nonzero on error.
  1203.  
  1204.       See Also:
  1205.       init.
  1206.  
  1207.       Example:
  1208.        see constructor example.
  1209.  
  1210.     _________________________________________________________
  1211.      virtual void disconnect(void);
  1212.       Description:
  1213.       This function is intended for when the serial port is connected to a
  1214.       hayes compatible modem.  Disconnect attempts to break the connection
  1215.       by dropping DTR, if that doesn't work then the classic +++ followed
  1216.       by ATH is sent.
  1217.  
  1218.       Returns:
  1219.       nonzero on error.
  1220.  
  1221.       See Also:
  1222.       dtr.
  1223.  
  1224.       Example:
  1225.        see constructor example.
  1226.  
  1227.  
  1228.     _________________________________________________________
  1229.      void dtr(int i);
  1230.       Description:
  1231.        i - State of DTR:1=on, 0=off.
  1232.       This function allows you to set the state of the DTR line.  Call it
  1233.     with 1 to raise DTR, zero to lower DTR.
  1234.  
  1235.       Returns:
  1236.       nothing.
  1237.  
  1238.       See Also:
  1239.  
  1240.       Example:
  1241.        void COMIO::disconnect()
  1242.         {
  1243.         int i;
  1244.  
  1245.         dtr(0);// Attempt to disconnect using DTR
  1246.         sleep(30);
  1247.         dtr(1)
  1248.  
  1249.         if(!carrier())// If no carrier then we are done
  1250.          return;
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.         for(i=0;i<=2;i++)
  1261.          {
  1262.          COMIO::put('+');
  1263.          sleep(30);
  1264.          }
  1265.         sleep(15);
  1266.         COMIO::putstr("\rATH0\r");
  1267.         }
  1268.  
  1269.  
  1270.     _________________________________________________________
  1271.      void flush_in(void);
  1272.       Description:
  1273.       This function will clear out the current inbound buffer, and any
  1274.       characters that may arrive while clearing.  It will not return until
  1275.       the hit function returns a zero.
  1276.       Returns:
  1277.       nothing
  1278.       See Also:
  1279.       flush_out,purge_in,purge_out
  1280.  
  1281.     _________________________________________________________
  1282.      void flush_out(void);
  1283.       Description:
  1284.        This functions for the operating system to transmit any characters
  1285.     waiting in the out buffer.
  1286.  
  1287.       Returns:
  1288.       nothing.
  1289.  
  1290.       See Also:
  1291.       flush_in,purge_in,purge_out
  1292.  
  1293.  
  1294.  
  1295.     _________________________________________________________
  1296.      virtual BYTE get(BYTE *ch);
  1297.       Description:
  1298.        ch - Pointer to where to store read character(if not NULL).
  1299.       This function receives the next 8-bit character from the serial port.
  1300.     If none are available then this function returns a zero.  There are two
  1301.     paths by which this function returns its data.  First is through the
  1302.     normal function return, and second i
  1303.     s via a pointer to a BYTE.  If you do not wish to use the pointer
  1304.     method simply call it as "get(NULL)".  Example: "x=get(NULL)",
  1305.     "get(&x)" and "x=get(&x)" all do exactly the same thing.
  1306.  
  1307.       Returns:
  1308.       character read.
  1309.  
  1310.       See Also:
  1311.       put,getstr,hit.
  1312.  
  1313.       Example:
  1314.        see constructor example.
  1315.  
  1316.      _________________________________________________________
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.      virtual int hit(void);
  1326.       Description:
  1327.       Hit allows you to determine if there is a character waiting to be
  1328.       received(by one of the input functions).  Hit returns 0 if none
  1329.       available. If data is waiting it returns the number of bytes waiting.
  1330.  
  1331.       Returns:
  1332.       true if there is a character available.
  1333.  
  1334.       See Also:
  1335.        get,wait2get.
  1336.  
  1337.       Example:
  1338.        see constructor example.
  1339.  
  1340.  
  1341.  
  1342.     _________________________________________________________
  1343.      int init(int p);
  1344.       Description:
  1345.        p - the comport that you want to use.
  1346.       Opens hardware comport p and attaches it to this object.
  1347.  
  1348.       Returns:
  1349.       nonzero on error.
  1350.  
  1351.       See Also:
  1352.       ~COMIO.
  1353.  
  1354.       Example:
  1355.        see constructor example.
  1356.     _________________________________________________________
  1357.      void purge_in(void);
  1358.       Description:
  1359.       This function will erase any characters that are currently in the
  1360.       input buffer.
  1361.       Returns:
  1362.       nothing
  1363.       See Also:
  1364.       flush_in,flush_out,purge_out
  1365.  
  1366.     _________________________________________________________
  1367.      void purge_out(void);
  1368.       Description:
  1369.        This function removes any characters from the output buffer, causing
  1370.     them to never be transmitted.
  1371.  
  1372.       Returns:
  1373.       nothing.
  1374.  
  1375.       See Also:
  1376.       flush_out,flush_in,purge_in
  1377.  
  1378.  
  1379.  
  1380.  
  1381.     _________________________________________________________
  1382.      virtual int put(BYTE ch);
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.       Description:
  1392.        ch - the character to be written.
  1393.       This function will attempt to write a single character to the device.
  1394.     If the operation is successful this function will return a zero.
  1395.  
  1396.       Returns:
  1397.       nonzero on error.
  1398.  
  1399.       See Also:
  1400.       get,putstr,printf.
  1401.  
  1402.       Example:
  1403.        see constructor example.
  1404.  
  1405.  
  1406.     _________________________________________________________
  1407.      int putstr(char *str);
  1408.       Description:
  1409.        str - the string or modem command.
  1410.       This function is used primarily for modem commands.  If the string
  1411.     starts with the letters AT then the string is assumed to be a modem
  1412.     command and some extra processing is done.  Otherwise the string is
  1413.     simply written to the serial port.  Modem str
  1414.     ings may have the following characters imbedded in them:
  1415.  
  1416.      | (pipe) = carriage return
  1417.      {  = carriage return
  1418.      v(lowercase)= drop dtr
  1419.      ^(carrot) = raise dtr
  1420.  
  1421.       Returns:
  1422.       zero on success.
  1423.  
  1424.       See Also:
  1425.  
  1426.  
  1427.     _________________________________________________________
  1428.      virtual int timed_get(BYTE *ch,int secs);
  1429.       Description:
  1430.        ch - pointer to where to store read character.
  1431.        secs-how many tenths of a second to wait for the character.
  1432.       This function receives the next 8-bit character from the serial port.
  1433.     If none are available then this waits secs 1/10ths of a seconds for one
  1434.     to arrive.  If a character was found before timeout this function
  1435.     returns 0, otherwise a one is returned.
  1436.       The actual character is returned by the ch pointer.
  1437.  
  1438.       Returns:
  1439.       nonzero on error.
  1440.  
  1441.       See Also:
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.     CLASS NAME: ALP       PARENT: COMIO
  1458.     IMPORTANT CHILDREN: none
  1459.  
  1460.     Definition:
  1461.     struct ALP:public COMIO
  1462.     {
  1463.     public:
  1464.      ALP();
  1465.      void update(void);// Call this as often as possible
  1466.      void intr(void);
  1467.      int check(void);  // Check for ALP-compat device on remote side
  1468.      void transmit(void); // transmit a packet
  1469.  
  1470.      // Replacements for CONIO functions:
  1471.      virtual int put(BYTE ch);
  1472.      virtual BYTE get(BYTE *ch);
  1473.      virtual int hit(void);
  1474.      virtual void disconnect();
  1475.  
  1476.      char str[2000];
  1477.      int p;
  1478.      BYTE intrans;
  1479.      BYTE no_alp;
  1480.  
  1481.     private:
  1482.      // Incoming queue
  1483.      void push(BYTE ch);
  1484.      BYTE pop(void);
  1485.  
  1486.      void input(BYTE ch);
  1487.  
  1488.      BYTE hi,lo;
  1489.      BYTE in_packet[2048];
  1490.      BYTE uncomp[2048];
  1491.      BYTE phase;
  1492.      int in_length;
  1493.      int in_num;
  1494.      unsigned short in_crc;
  1495.      unsigned short in_tcrc;
  1496.      int in_loc;
  1497.  
  1498.      BYTE queue[ALP_IN];
  1499.      int front,back;
  1500.  
  1501.      int background;
  1502.      BYTE outnum;
  1503.      BYTE lastnum;
  1504.     };
  1505.  
  1506.  
  1507.     Description:
  1508.      ALP(Anti Line noise Protocol) is a replacement for COMIO that ensures
  1509.     a 2-way reliable serial connection.  Data is sent out in packets(which
  1510.     are compressed using the LZSS protocol) that are verified to insure a
  1511.     reliable link.  It is 100% compatible
  1512.     with the COMIO object.  This communications standard allows separate
  1513.     MULTI-APP applications to have a common hi-level method of
  1514.     communication.  When using ALP you can use put,get and all the other
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.     COMIO functions and let ALP worry about the error che
  1524.     cking.  Except for the update function none of the additional contents
  1525.     of this class are of any real use to the application programmer.
  1526.  
  1527.  
  1528.     Data Members:
  1529.      BYTE intrans;
  1530.       Intrans is a flag that tells if a packet is in transit or not.  If a
  1531.     packet is in-transit it means that the packet has been sent, yet ALP is
  1532.     unsure if it made it through correctly or not.  Intrans holds 1 if
  1533.     block is in transit, zero if not.
  1534.  
  1535.      BYTE no_alp;
  1536.       no_alp is a flag that tells if ALP is enabled or not.  If ALP is
  1537.     disabled then all calls are passed directly through to the COMIO
  1538.     object.
  1539.  
  1540.      int p;
  1541.       P tells ALP how many characters are in the str  buffer waiting to go
  1542.     out in the next packet.  See str  for more details.
  1543.  
  1544.      char str[2000];
  1545.       This is the buffer where outgoing data is held until it is packeted.
  1546.     This variable is made public because it is perfectly legal to memcopy
  1547.     stuff into str and modify p  directly.  This is particularly appealing
  1548.     in file transfer situation as it cuts
  1549.      the overhead induced by the COMIO replacements.
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.     Member Functions:
  1556.      ALP();
  1557.       Description:
  1558.       CONSTRUCTOR - The ALP constructor sets up all buffers and initialized
  1559.       all pointers.
  1560.  
  1561.       Returns:
  1562.       nothing.
  1563.  
  1564.       See Also:
  1565.  
  1566.       Example:
  1567.       // VTERM-ALP is a simple tty terminal that must be provided with a
  1568.       DEVICE to use
  1569.       // as a console.  This console is usually something such as the UI's
  1570.       CONIO object
  1571.       // however it can really be anything, even another COMIO(which would
  1572.       provide a
  1573.       // remote terminal.  Press \ for a list of commands in this terminal.
  1574.       // This example is very similar to the example given in COMIO, this
  1575.       shows how
  1576.       // compatible these two classes are.
  1577.       void vterm(DEVICE *con,ALP *com)
  1578.       {
  1579.       // con - console device
  1580.       // com - "modem" interface
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.       int done=0;
  1590.       char ch;// Check for commands
  1591.  
  1592.        com->baud(2400);// Default to 2400 baud
  1593.  
  1594.        while(!done)
  1595.         {
  1596.         com->update();// For ALP to packet everything when needed
  1597.  
  1598.         if(con->hit())// Output keypress
  1599.          {
  1600.          ch=con->get(NULL);
  1601.          if(ch!='\')
  1602.           com->put(con->get(NULL));
  1603.          }
  1604.  
  1605.         if(com->hit())// Display incoming data
  1606.          con->put(com->get(NULL));
  1607.  
  1608.         if(ch=='\')
  1609.          {
  1610.          char str[100];
  1611.          con->reset();
  1612.          con->putstr("Select an option: <B>aud <D>isconnect,<A>lp  or
  1613.          <Q>uit? ");
  1614.          switch( toupper(con->wait2get(NULL)))
  1615.           {
  1616.           case Q':done=1;break;
  1617.           case D':com->disconnect();break;
  1618.           case B':con->putstr("\rWhat baud? ");
  1619.            con->getstr(str);
  1620.            con->baud(atoi(str));
  1621.            break;
  1622.           case A':
  1623.            if(com->check())
  1624.             con->putstr("ALP active\r");
  1625.            break;
  1626.           }
  1627.          }
  1628.         }
  1629.       }
  1630.  
  1631.     _________________________________________________________
  1632.      int check(void);
  1633.       Description:
  1634.       This function is used to establish an ALP session.  Check transmits
  1635.       the ALP init string and waits for a reply.  If the other side
  1636.       replies(it does this automatically via update) then both sides no_alp
  1637.       values gets set to zero and an ALP session begi
  1638.     ns.
  1639.  
  1640.       Returns:
  1641.       TRUE if ALP link has been established.
  1642.  
  1643.       See Also:
  1644.       update,intr.
  1645.  
  1646.       Example:
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.        see constructor example.
  1656.  
  1657.  
  1658.     _________________________________________________________
  1659.      virtual void disconnect(void);
  1660.       Description:
  1661.       This function is intended for when the serial port is connected to a
  1662.       hayes compatible modem.  Disconnect first ends the ALP session.  Then
  1663.       disconnect attempts to break the connection by dropping DTR, if that
  1664.       doesn't work then the classic +++ follow
  1665.     ed by ATH is sent.
  1666.  
  1667.      Returns:
  1668.       nothing.
  1669.  
  1670.      See Also:
  1671.       dtr.
  1672.  
  1673.      Example:
  1674.        see constructor example.
  1675.  
  1676.     _________________________________________________________
  1677.      void dtr(int i);
  1678.       Description:
  1679.        i - State of DTR:1=on, 0=off.
  1680.       This function allows you to set the state of the DTR line.  Call it
  1681.     with 1 to raise DTR, zero to lower DTR.
  1682.  
  1683.       Returns:
  1684.       nothing.
  1685.  
  1686.       See Also:
  1687.  
  1688.       Example:
  1689.        void COMIO::disconnect()
  1690.         {
  1691.         int i;
  1692.  
  1693.         dtr(0);// Attempt to disconnect using DTR
  1694.         sleep(30);
  1695.         dtr(1)
  1696.  
  1697.         if(!carrier())// If no carrier then we are done
  1698.          return;
  1699.  
  1700.         for(i=0;i<=2;i++)
  1701.          {
  1702.          COMIO::put('+');
  1703.          sleep(30);
  1704.          }
  1705.         sleep(15);
  1706.         COMIO::putstr("\rATH0\r");
  1707.         }
  1708.  
  1709.     _________________________________________________________
  1710.      void flow(int i);
  1711.       Description:
  1712.        i - flow control type:
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.         0 = NONE
  1722.         1 = CTS/RTS(hardware)
  1723.         2 = XON/XOFF(software)
  1724.         3 = both hardware and software
  1725.  
  1726.       This function sets the flow control mode of the serial port.  This is
  1727.     useful for high speed modems.
  1728.  
  1729.       Returns:
  1730.       nothing.
  1731.  
  1732.       See Also:
  1733.     _________________________________________________________
  1734.      virtual BYTE get(BYTE *ch);
  1735.       Description:
  1736.        ch - Pointer to where to store read character(if not NULL).
  1737.       This function receives the next 8-bit character from the ALP driver.
  1738.     If none are available then this function returns a zero.  There are two
  1739.     paths by which this function returns its data.  First is through the
  1740.     normal function return, and second is
  1741.      via a pointer to a BYTE.  If you do not wish to use the pointer method
  1742.     simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
  1743.     "x=get(&x)" all do exactly the same thing.
  1744.  
  1745.       Returns:
  1746.       the character read.
  1747.  
  1748.       See Also:
  1749.       getstr,put,hit.
  1750.  
  1751.       Example:
  1752.        see constructor example.
  1753.  
  1754.     _________________________________________________________
  1755.      virtual int hit(void);
  1756.       Description:
  1757.       Hit allows you to determine if there is a character waiting to be
  1758.       received(by one of the input functions).  Hit returns 0 if none
  1759.       available. If data is waiting it returns the number of bytes waiting.
  1760.  
  1761.       Returns:
  1762.       the number of characters waiting to be read.
  1763.  
  1764.       See Also:
  1765.        get.
  1766.  
  1767.       Example:
  1768.        see constructor example.
  1769.  
  1770.  
  1771.  
  1772.     _________________________________________________________
  1773.      void intr(void);
  1774.       Description:
  1775.       Intr is similar to update, except that it is intended to be called
  1776.       from an interrupt if that is how you desire to make sure ALP stays
  1777.       updated.
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.       Returns:
  1788.       nothing.
  1789.  
  1790.       See Also:
  1791.        update.
  1792.  
  1793.     _________________________________________________________
  1794.      virtual int put(BYTE ch);
  1795.       Description:
  1796.        ch - character to be written.
  1797.       This function will attempt to write a single character to the device.
  1798.     If the operation is successful this function will return a zero.
  1799.  
  1800.       Returns:
  1801.       nonzero on error.
  1802.  
  1803.       See Also:
  1804.        printf,putstr.
  1805.  
  1806.       Example:
  1807.        see constructor example.
  1808.  
  1809.     _________________________________________________________
  1810.      void transmit(void);
  1811.       Description:
  1812.       Transmit will force a packet to be transmitted.
  1813.  
  1814.       Returns:
  1815.       nothing.
  1816.  
  1817.       See Also:
  1818.  
  1819.  
  1820.     _________________________________________________________
  1821.      void update(void);
  1822.       Description:
  1823.       Update should be called as often as possible, as it checks the
  1824.       incoming data line for packets and transmits any waiting data in a
  1825.       packet.
  1826.  
  1827.       Returns:
  1828.       nothing.
  1829.       See Also:
  1830.        intr.
  1831.  
  1832.       Example:
  1833.        see constructor example.
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.     CLASS NAME: FILEIO       PARENT: DEVICE
  1854.     IMPORTANT CHILDREN: none
  1855.  
  1856.     Definition:
  1857.  
  1858.     class FILEIO:public DEVICE
  1859.      {
  1860.      public:
  1861.      FILEIO();
  1862.      ~FILEIO();
  1863.      int gethandle(void);
  1864.  
  1865.      void open_file(char *path,char *name,char md,char *type,char
  1866.     *creator);
  1867.  
  1868.      void fread(void *loc,long len);
  1869.      void fwrite(void *loc,long len);
  1870.      char end(void);
  1871.      char error(void);
  1872.      void close_file(void);
  1873.      void pos(long loc);
  1874.      long where(void);
  1875.  
  1876.      virtual int put(BYTE ch);
  1877.      virtual BYTE get(BYTE *ch);
  1878.      char sharing;
  1879.      char filename[80];
  1880.      };
  1881.  
  1882.  
  1883.  
  1884.     Description:
  1885.      FILEIO provides a platform-independent method for accessing files.  It
  1886.     is setup exactly like any other MGBBS DEVICE.  Support is provided for
  1887.     file sharing(in platforms that support it).  All single character
  1888.     commands are buffered to provide maximum
  1889.     speed.
  1890.  
  1891.  
  1892.  
  1893.     Data Members:
  1894.      char sharing;
  1895.       Holds 1 if file sharing is on, 0 if it is off(set by user).
  1896.      char filename[80];
  1897.       Holds the full file name(including path).
  1898.  
  1899.     Member Functions:
  1900.      FILEIO();
  1901.       Description:
  1902.       CONSTRUCTOR - sets up all pointers, handles etc.
  1903.  
  1904.       Returns:
  1905.       nonzero on error.
  1906.  
  1907.       See Also:
  1908.  
  1909.       Example:
  1910.        int copyfile(char *source_path,char *source_name,char
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.     *dest_path,char *dest_name)
  1920.        {// This function will copy a file.  Please note that this function
  1921.     will only copy the
  1922.        // data fork of a Macintosh File.
  1923.        FILE *in,*out;
  1924.  
  1925.        in=new FILEIO;
  1926.        out=new FILEIO;
  1927.  
  1928.        in->open_file(source_path,source_name,'r',"","");
  1929.        out->open_file(dest_path,dest_name,'w',"","");
  1930.  
  1931.        if(in->error() || out->error() )
  1932.         {
  1933.         delete in;// Delete both file objects(this will close either if
  1934.         they were opened)
  1935.         delete out;
  1936.         return 1;// return an error condition
  1937.         }
  1938.  
  1939.        while(!in->end())// Loop until end-of-file is reached
  1940.         out->put(in->get(NULL));
  1941.  
  1942.        in->close_file();
  1943.        out->close_file();
  1944.        }
  1945.  
  1946.  
  1947.     _________________________________________________________
  1948.      ~FILEIO();
  1949.       Description:
  1950.       DESTRUCTOR - closes file if open.
  1951.  
  1952.       Returns:
  1953.       nonzero on error.
  1954.  
  1955.       See Also:
  1956.  
  1957.     _________________________________________________________
  1958.      void close_file(void);
  1959.       Description:
  1960.       This function will close the file, allowing the same data structure
  1961.       to be used for another file.
  1962.  
  1963.       Returns:
  1964.       nonzero on error.
  1965.  
  1966.       See Also:
  1967.  
  1968.  
  1969.  
  1970.     _________________________________________________________
  1971.      char end(void);
  1972.       Description:
  1973.       This function returns true if the end of the file has been reached.
  1974.  
  1975.       Returns:
  1976.       nonzero on error.
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.       See Also:
  1987.  
  1988.  
  1989.     _________________________________________________________
  1990.      char error(void);
  1991.       Description:
  1992.       This function returns true if the file is in an error condition.
  1993.  
  1994.       Returns:
  1995.       nonzero on error.
  1996.  
  1997.       See Also:
  1998.  
  1999.     _________________________________________________________
  2000.     void fwrite(void *loc,long len);
  2001.       Description:
  2002.        loc - The location in memory your writing from.
  2003.        len - The length of the block being written.
  2004.       This function, which is similar to the <stdio.h> function of the same
  2005.     name, allows you to write something pointed to by loc  of length len to
  2006.     the file.
  2007.  
  2008.       Returns:
  2009.       nonzero on error.
  2010.  
  2011.       See Also:
  2012.  
  2013.  
  2014.     _________________________________________________________
  2015.      void fread(void *loc,long len);
  2016.       Description:
  2017.        loc - Pointer to the location in memory to hold block
  2018.        len - The length of the file you wish to read.
  2019.       This function, which is similar to the <stdio.h> function of the same
  2020.     name, allows you to read something into an area pointed to by loc  of
  2021.     length len  from the file.
  2022.  
  2023.       Returns:
  2024.       nonzero on error.
  2025.  
  2026.       See Also:
  2027.  
  2028.  
  2029.     _________________________________________________________
  2030.      virtual BYTE get(BYTE *ch);
  2031.       Description:
  2032.        ch - Pointer to where to store read character(if not NULL).
  2033.       This function receives the next 8-bit character from the device.  If
  2034.     none are available then this function returns a zero.  There are two
  2035.     paths by which this function returns its data.  First is through the
  2036.     normal function return, and second is via
  2037.      a pointer to a BYTE.  If you do not wish to use the pointer method
  2038.     simply call it as "get(NULL)".  Example: "x=get(NULL)", "get(&x)" and
  2039.     "x=get(&x)" all do exactly the same thing.
  2040.  
  2041.       Returns:
  2042.       nonzero on error.
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.       See Also:
  2053.  
  2054.  
  2055.  
  2056.     _________________________________________________________
  2057.      int gethandle(void);
  2058.       Description:
  2059.       Most operating systems use a single integer to reference a file. If
  2060.       the operations system your using MULTI-APP in supports such file
  2061.       referencing this function returns that value.  Use of this function
  2062.       should be avoided, as it can cause code created
  2063.      for MULTI-APP to be incompatible on other platforms.
  2064.  
  2065.       Returns:
  2066.       nonzero on error.
  2067.  
  2068.       See Also:
  2069.  
  2070.  
  2071.     _________________________________________________________
  2072.      void open_file(char *path,char *name,char md,char *type,char
  2073.     *creator);
  2074.       Description:
  2075.        path - The location in the file system of the file.
  2076.        name - The actual name of the file.
  2077.        md - The access mode your using for the file.
  2078.        type - The 4 character file type(only used on some OS's)
  2079.        mode - The 4 character file signature(only used on some OS's)
  2080.       This function is used to tell FILEIO which fill it will be accessing.
  2081.     You can specify both a path and a name.  md should be one of the
  2082.     following:
  2083.       r' for reading(other users are allowed to also read)
  2084.       w' for writing and truncation(other users must wait to access file)
  2085.       +' both read and write(other users must wait to access file)
  2086.       s' for both read/write(other uses may have full access to file)
  2087.       a' for appended write(other users must wait to access file)
  2088.       The type and creator allow you to specify these fields if your
  2089.       operating system supports them.  The w' command will erase anything
  2090.       that was in the file beforehand.  If you wish to write a single
  2091.       record in a file you must open with the +' command, e
  2092.     ven if you will not be reading.
  2093.  
  2094.       Returns:
  2095.       nonzero on error.
  2096.  
  2097.       See Also:
  2098.  
  2099.  
  2100.  
  2101.     _________________________________________________________
  2102.      void pos(long loc);
  2103.       Description:
  2104.        loc - Location in bytes to place file pointer.
  2105.       This function will position the file position at loc.
  2106.  
  2107.       Returns:
  2108.       nonzero on error.
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.       See Also:
  2119.  
  2120.     _________________________________________________________
  2121.      virtual int put(BYTE ch);
  2122.       Description:
  2123.        ch - The character to be written to the file.
  2124.       This function will attempt to write a single character to the device.
  2125.     If the operation is successful this function will return a zero.
  2126.  
  2127.       Returns:
  2128.       nonzero on error.
  2129.  
  2130.       See Also:
  2131.  
  2132.     _________________________________________________________
  2133.      long where(void);
  2134.       Description:
  2135.       This function will return the current file position.
  2136.  
  2137.       Returns:
  2138.       nonzero on error.
  2139.  
  2140.       See Also:
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.     CLASS NAME: STACK      PARENT: NONE
  2184.     IMPORTANT CHILDREN: NONE
  2185.  
  2186.     Definition:
  2187.     class STACK
  2188.     {
  2189.     public:
  2190.      STACK();
  2191.      int pop(void);
  2192.      void push(int v);
  2193.      int empty(void);
  2194.  
  2195.     private:
  2196.      int location;
  2197.      int stack[STACK_SIZE];
  2198.     };
  2199.  
  2200.  
  2201.     Description:
  2202.      Stack sets up a stack(FIFO) to hold integers.  This stack may be upto
  2203.     STACK_SIZE in length.
  2204.  
  2205.  
  2206.     Data Members:
  2207.      NONE
  2208.  
  2209.     Member Functions:
  2210.      STACK();
  2211.       CONSTRUCTOR - sets up a empty stack.
  2212.  
  2213.      int pop(void);
  2214.       Pops an integer from the stack.
  2215.  
  2216.      void push(int v);
  2217.       Pushes an integer onto the stack.
  2218.  
  2219.      int empty(void);
  2220.       This function allows you to tell if a stack is empty.  It returns
  2221.     nonzero if the stack has items, zero if there are none.
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.     Glossary
  2250.     BAUD - the communication rate between two devices. Baud rates usually
  2251.     range from 300 to 38400 baud.
  2252.     CARRIER - is a signal generated by a remote modem to say that it is
  2253.     still on-line.  In any serious communications program carrier must be
  2254.     repeatedly checked to ensure the remote modem is still connected.
  2255.     CREATOR - a file ID used by some operating systems(most notably the
  2256.     Mac) that allows data files to know "who created them."
  2257.     DATA CONTAINER - A dynamic holding area for data that can shrink or
  2258.     grow to handle the amount of data sent.  Data containers usually store
  2259.     data in some predetermined way.
  2260.     DTR - The software on/off switch for a modem.  If DTR is lowered the
  2261.     modem hangs up and will not accept any commands until the DTR is
  2262.     raised.
  2263.     DYNAMIC - Able to change to meet the situation at hand.  Dynamic
  2264.     containers only take up the amount of memory needed.
  2265.     FALSE - A value is said to be false when it contains a zero.
  2266.     FIFO - "First In First Out" a way of describing how a data container
  2267.     works, usually associated with a queue.
  2268.     FILE TYPE - some operating systems(most notably the Mac) allow you to
  2269.     assign a file type to any file you open.
  2270.     HAYES COMPAT - A type of modem that understands the hayes AT style
  2271.     command.  A hayes modem receives all its commands over the data lines,
  2272.     rather than the special control lines.
  2273.     INTERRUPT - When the computer stops doing what it was doing to handle
  2274.     something that has happened.
  2275.     INTERRUPT DEVICE - A device that stops the computers processing to
  2276.     handle its changed state.
  2277.     LINE NOISE - Errors that commonly occur in data communication caused by
  2278.     bad phone lines.
  2279.     LIFO - "Last In First Out" a way of describing how a data container
  2280.     works, usually associated with a stack.
  2281.     LINKED LIST - A sort of dynamic array.  A linked list holds a series of
  2282.     elements in some predetermined order.
  2283.     MODAL-A window that once on your screen is the only thing that you can
  2284.     access until it is "dismissed."
  2285.     MODELESS-A window that can be moved to the background by clicking
  2286.     another window on the screen.
  2287.     POLLED DEVICE - A device that generates no interrupt when its state
  2288.     changes, but rather must be polled to determine if it is ready.  All
  2289.     devices in MULTI-APP are polled.
  2290.     QUEUE - A data container commonly put between to devices of differing
  2291.     speeds.  A queue will accept information and release it in the same
  2292.     order as it got it.  Think of a queue as a one-way street, only one
  2293.     entrance and only one exit.
  2294.     STACK - A data container commonly used when you want to leave something
  2295.     the same way you came.  A stack will accept information and release the
  2296.     last item you entered, then the 2nd to last and so on.  Think of a
  2297.     stack as a restaurant plate holder, you
  2298.      can only get the plate on the top.  If you want to get the bottom
  2299.     plate you must remove all plates.
  2300.     TRUE - A value is said to be true when it holds any value other than
  2301.     zero.
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.